package com.linkgie.galaxyframework.httpproxy.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import com.linkgie.galaxyframework.httpproxy.HttpMethod;
import com.linkgie.galaxyframework.httpproxy.HttpStatusException;
import com.linkgie.galaxyframework.httpproxy.RequestParamFilter;
import com.linkgie.galaxyframework.httpproxy.ResponseConverter;
import com.linkgie.galaxyframework.httpproxy.ResponseHandler;

/**
 * HTTP 服务方法；
 * 
 * @author haiq
 *
 */
@Target({ ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
public @interface HttpRequest {

	/**
	 * 请求路径；
	 * 
	 * 默认为空；
	 * 
	 * 此时按照 service 的 path 属性+方法名 产生最终的请求路径；
	 * 
	 * @return
	 */
	public String path() default "";

	/**
	 * HTTP 请求方法;
	 * 
	 * @return
	 */
	public HttpMethod method();

	/**
	 * HTTP 的 Content-Type;
	 * 
	 * @return
	 */
	public String contentType() default "";

	/**
	 * 自定义的返回值转换器；必须实现 {@link RequestParamFilter} 接口；
	 * 
	 * @return
	 */
	public Class<? extends RequestParamFilter> requestParamFilter() default RequestParamFilter.class;

	/**
	 * 自定义的返回值转换器；必须实现 {@link ResponseConverter} 接口；
	 * <p>
	 * 注：<br>
	 * 此方法在 2.8.9.RELEASE 版本已被废弃， 请使用 {@link #responseHandler()} 代替；
	 * <p>
	 * 对于使用了此方法的历史代码，目前仍然会兼容使用此方法的定义；
	 * <p>
	 * 当同时定义了此方法和 {@link #responseHandler()} 时，优先采用 {@link #responseHandler()} 的定义；
	 * @return
	 */
	@Deprecated
	public Class<? extends ResponseConverter> responseConverter() default ResponseConverter.class;

	/**
	 * 自定义的返回值处理器；必须实现 {@link ResponseHandler} 接口；
	 * <p>
	 * 如果未设置，则默认使用 {@link DefaultResponseHandlerFactory} 产生的默认返回值处理器；
	 * <p>
	 * 此方法替换了已不推荐的方法 {@link #responseConverter()}， 当同时定义两者时，优先采用此方法的定义；
	 * 
	 * @return
	 */
	public Class<? extends ResponseHandler> responseHandler() default ResponseHandler.class;

	/**
	 * 当检测到 http 错误时是否在引发的 {@link HttpStatusException} 中包含回复的内容；
	 * 
	 * 默认为 false；
	 * 
	 * @return
	 */
	public boolean resolveContentOnHttpError() default false;
}
